﻿// Project: Salient
// http://salient.codeplex.com
// 
// Copyright 2010, Sky Sanders <sky at skysanders.net>
// licensed under the GPL Version 2 licenses.
// http://salient.codeplex.com/license
// 
// 
// You may use this code under the terms of the GNU General Public 
// License (GPL) Version 2.
using System.Net;
namespace Salient.Net
{
    /// <summary>
    ///   IGateway acts as a throttled and cached single point of origin for http requests. 
    ///   IGateway must be thread-safe.
    /// </summary>
    public interface IGateway
    {
        /// <summary>
        ///   <para>This method first checks the cache for the specified url, if found the process results are returned immediately.</para>
        ///   <para>If a cached result is not found, the request is throttled as per the ThrottleInterval, and upon release, an AsyncResult is returned.</para>
        ///   <para>Upon successful completion of the request, the response text is passed to the requestHandler, which returns an instance of T.</para>
        ///   <para>This value is cached after the callback completes, allowing the callback to examine and modify the results before caching.</para>
        /// </summary>
        /// <typeparam name = "T">The type that is returned by the requestHandler</typeparam>
        /// <param name = "url">The path of the request.</param>
        /// <param name = "cacheRule">
        ///   <para>The rule to apply when getting/setting from the gateway cache. </para>
        ///   <para>e.g. for StackOverflow API, this would be the route. 
        ///     '/sites' should have a rule of 2 hours applied.</para>
        /// </param>
        /// <param name = "bypassCache">whether to bypass the gateway's cache</param>
        /// <param name = "timeout">when to force a timeout error, in ms.</param>
        /// <param name = "callback">The function that handles the completion of the request</param>
        /// <param name = "requestHandler">The function that processes the request and 
        ///   returns an instance of <typeparamref name = "T" /></param>
        /// <param name="state">State object to be used for request. Useful for tagging a request with an id via RequestState.Data</param>
        /// <returns></returns>
        GatewayAsyncResult<T> BeginGetResponse<T>(string url, string cacheRule, bool bypassCache, int? timeout, GatewayAsyncCallback<T> callback, GatewayRequestHandlerDelegate<T> requestHandler, GatewayRequestState state) where T : class, new();

        /// <summary>
        ///   <para>This method first checks the cache for the specified url, if found the process results are returned immediately.</para>
        ///   <para>If a cached result is not found, the request is throttled as per the ThrottleInterval, and upon release, an AsyncResult is returned.</para>
        ///   <para>Upon successful completion of the request, the response text is passed to the requestHandler, which returns an instance of T.</para>
        ///   <para>This value is cached after the callback completes, allowing the callback to examine and modify the results before caching.</para>
        /// </summary>
        /// <typeparam name = "T">The type that is returned by the requestHandler</typeparam>
        /// <param name = "url">The path of the request.</param>
        /// <param name = "cacheRule">
        ///   <para>The rule to apply when getting/setting from the gateway cache. </para>
        ///   <para>e.g. for StackOverflow API, this would be the route. 
        ///     '/sites' should have a rule of 2 hours applied.</para>
        /// </param>
        /// <param name = "bypassCache">whether to bypass the gateway's cache</param>
        /// <param name = "timeout">when to force a timeout error, in ms.</param>
        /// <param name = "callback">The function that handles the completion of the request</param>
        /// <param name = "requestHandler">The function that processes the request and 
        ///   returns an instance of <typeparamref name = "T" /></param>
        /// <returns></returns>
        GatewayAsyncResult<T> BeginGetResponse<T>(string url, string cacheRule, bool bypassCache, int? timeout, GatewayAsyncCallback<T> callback, GatewayRequestHandlerDelegate<T> requestHandler) where T : class, new();


        /// <summary>
        ///   <para>This method first checks the cache for the specified url, if found the process results are returned immediately.</para>
        ///   <para>If a cached result is not found, the request is throttled as per the ThrottleInterval, and upon release, an AsyncResult is returned.</para>
        ///   <para>Upon successful completion of the request, the response text is passed to the requestHandler, which returns an instance of T.</para>
        ///   <para>This value is cached after the callback completes, allowing the callback to examine and modify the results before caching.</para>
        /// </summary>
        /// <typeparam name = "T">The type that is returned by the requestHandler</typeparam>
        /// <param name = "url">The path of the request.</param>
        /// <param name = "callback">The function that handles the completion of the request</param>
        /// <param name = "requestHandler">The function that processes the request and 
        ///   returns an instance of <typeparamref name = "T" /></param>
        /// <returns></returns>
        GatewayAsyncResult<T> BeginGetResponse<T>(string url, GatewayAsyncCallback<T> callback, GatewayRequestHandlerDelegate<T> requestHandler) where T : class, new();



        /// <summary>
        ///   The minimum length of time to allow between requests.
        /// </summary>
        int ThrottleInterval { get; set; }

        /// <summary>
        ///   The user-agent header to apply to all requests.
        /// </summary>
        string UserAgent { get; set; }

        /// <summary>
        ///   The IGatewayCache that services this gateway.
        /// </summary>
        IGatewayCache Cache { get; set; }

#if !SILVERLIGHT
    /// <summary>
    /// The System.Net.IWebProxy instance assigned to this gateway.
    /// </summary>
        IWebProxy Proxy { get; set; }
#endif

    }
}
